package lumis.portal.crypto;

import lumis.portal.stability.StableMinor;

/**
 * Defines the methods a cipher must implement. The cipher implementation must
 * be thread-safe.
 * 
 * @version $Revision: 13082 $ $Date: 2011-05-27 16:03:12 -0300 (Fri, 27 May 2011) $
 * @since 5.5.0
 */
@StableMinor(version = "6.0", sinceVersion = "5.5")
public interface ICipher 
{
	/**
	 * Encrypts a string.
	 * @param value the original string.
	 * @return the encrypted string.
	 * @throws IllegalArgumentException if <code>value</code> is <code>null</code>.
	 * @since 5.5.0
	 */
	public String encrypt(String value);

	/**
	 * Decrypts a string.
	 * @param value the encrypted string.
	 * @return the string decrypted.
	 * @throws IllegalArgumentException if <code>value</code> is <code>null</code>.
	 * @throws InvalidEncryptedValueException if <code>value</code> is 
	 * incompatible with this cipher (probably was not encrypted by it or 
	 * is corrupted).
	 * @throws UnsupportedOperationException if this is a one-way cipher and
	 * does not support decryption.
	 * @since 5.5.0
	 */
	public String decrypt(String value) throws InvalidEncryptedValueException;
	
	/**
	 * Encrypts an array of bytes.
	 * @param value the original value.
	 * @return the encrypted value.
	 * @throws IllegalArgumentException if <code>value</code> is <code>null</code>.
	 * @since 5.5.0
	 */
	public byte[] encrypt(byte[] value);
	
	/**
	 * Decrypts an array of bytes.
	 * @param value the encrypted value.
	 * @return the value decrypted.
	 * @throws UnsupportedOperationException if this is a one-way cipher and
	 * does not support decryption.
	 * @throws IllegalArgumentException if <code>value</code> is <code>null</code>.
	 * @throws InvalidEncryptedValueException if <code>value</code> is 
	 * incompatible with this cipher (probably was not encrypted by it or 
	 * is corrupted).
	 * @since 5.5.0
	 */
	public byte[] decrypt(byte[] value) throws InvalidEncryptedValueException;
}
